Publishing with Quarto

Introduction to Data Science Workshop

Hiba Ahmad
Michelle Gandhi
21 Novemeber 2022

Table of Contents

  • Hello Quarto!

  • Key Features

  • R Markdown v/s Quarto

  • Publishing with Quarto

  • What can you Publish?

  • Authoring Quarto Documents

  • Rendering Quarto Documents

  • Publishing Services

  • Quarto Pub: An Overview

  • Publishing using Quarto Pub

  • Additional Resources

What is Quarto?

Hello Quarto!


Quarto® is an open-source, scientific and technical publishing system built on Pandoc.


It allows a user to:

  • Create dynamic content with Python, R, Julia, and Observable, as well as computing languages that don’t even exist at the moment.

  • Author documents as plain text markdown or Jupyter notebooks.

  • Publish high-quality articles, reports, presentations, websites, blogs, and books in HTML, PDF, MS Word, ePub, and more.

  • The goal of Quarto is to make the process of creating and collaborating dramatically better by unifying and extending the RMarkdown ecosystem!

The Big Picture!


Quarto and R Markdown share the same core team of developers - Carlos Scheidegger, Charles Teague, Christophe Dervirvieux, J.J. Allaire, Yihui Xie

Quarto Universe1


Key Features: The Next Gen R Markdown


  • Knitr started in 2011

  • RMarkdown started in 2014

  • Learnt from 10+years of literate programming with knitr + R Markdown

Quarto >>> R Markdown


  • Quarto and its enhancements are inbuilt with RStudio; no download necessary

  • Quarto allows unified syntax regardless of input format, engine and language

  • 40 different outputs available

  • Better accessibility and richer features

  • Quarto doesn’t rely on mandatory R run time


  • That said, if you heavily use access tools built around R Markdown such as blogdown, xaringan, workflowr and papaja, R Markdown might be better suited for you!

Publishing with Quarto

Publishing with Quarto

Author > Render > Publish

  • Quarto uses an engine like knitr to execute code and generate a temporary output(.md).. The .md file is processed via Pandoc & Quarto’s Lua filters to convert to a final output.

  • Multiple ways to publish documents, presentations, websites and more created using Quarto.

  • Output in standard formats such as HTML, PDF, MS Word etc. ensures that it can be published anywhere.

  • Quarto publish command publishes easily to various services such as GitHub, Netlify, RStudio Connect, etc.

  • Various other tools to publish from a Continuous Integration (CI) system.

Publishing with Quarto: The Process

1

What can you publish?


Through literate programming, Quarto can publish - presentations, websites, blogs, books and more!

Authoring

Authoring Quarto Documents

Elements of Markdown


Markdown is designed to be easy to write, and, even more importantly, easy to read.

Text Formatting

Code 
## Markdown allows you to format text as **bold** or *italics*. You can 
## also add superscripts^2^ or subscripts~2~, 
## and display code `verbatim`.

## You can also ~~strikethrough~~ text or present it in [caps]{.smallcaps}.

Markdown allows you to format text as bold or italics. You can also add superscripts2 or subscripts2, and display code verbatim.

You can also strikethrough text or present it in caps.

Authoring Quarto Documents

Math


Formulas in Quarto can be written using ‘$’.


Code 
## The area of circle is $A = \pi r^2$
## Basic algebra formula: $a^2- b^2 = (a+b)(a-b)$


The area of circle is \(A = \pi r^2\)

Basic algebra formula: \(a^2- b^2 = (a+b)(a-b)\)

Authoring Quarto Documents

Links and Images


You can embed links with names or direct urls like https://quarto.org/.

For images, the syntax is as follows:

Code 
## You can embed [links with names](https://quarto.org/) or
## direct urls like <https://quarto.org/>.

## For images, the syntax is ![Linking Images](IDS07.jpg){width="75%"}

Authoring Quarto Documents

Tables


Personal Ranking of Fruits

Code 
## |          | Mango  | Apple  | Orange |
## |:---------|:-------|-------:|:------:|
## | Hiba     | 1      |      2 | 3      |
## | Michelle | 2      |      3 | 1      |
Mango Apple Orange
Hiba 1 2 3
Michelle 2 3 1

Rendering

Rendering Quarto Documents


Way 1: Using the Render Button


Rendering Quarto Documents


Way 2: Using the Command Line


Rendering Quarto Documents


Way 1: Using the Quarto Package


Short Exercise


  • Download the material and open Coldplay.qmd.

  • Render the file using any of the three above-mentioned ways.

  • Do you see some cool features that are different from an .rmd file?

Solutions - we’ll discuss these further in our tutorial!


  • Automatically produces a table of contents

  • Links webpages

  • Links footnotes and the text

  • Text can be bold, italic, subscript and superscript

  • Option to strikethrough text

  • Can add tables

  • Option to add ordered and unordered list

  • Option to use different types of headers

  • Can add images with captions

  • Can change alignment of text and images

  • Automatically adds page numbers to the file

Publishing

Publishing Services


  • Quarto Pub: A free publishing service for content created with Quarto - ideal for blogs, course or project websites, books, presentations, and personal hobby sites

  • GitHub Pages: A website hosting service - enables publishing content based on source code managed within a GitHub repository

  • RStudio Connect: A publishing platform for secure sharing of data products within an organization (rather than for public use)

  • Netlify: A professional web publishing platform with support for many advanced features including custom domains, authentication, branch previews, and instant rollbacks - a free plan ideal for personal projects, hobby sites, experiments

  • Other Services - Firebase, Site44, Amazon S3

Quarto Pub: An Overview


There are two ways to publish content to Quarto Pub

  • Use the quarto publish command to publish content rendered on your local machine (recommended approach for beginners).

  • For GithHub users, use GitHub Action to automatically render your project and publish the resulting content whenever the code changes.

Before you can publish anything, a (free) Quarto Pub account has to be created. We’ll do this together in our tutorial!

Publishing Using Quarto Pub

Quarto Publish Command


Easiest way to publish locally rendered content -

  • Step 1: Check whether the terminal is at the directory where your project is located

  • Step 2: Execute the quarto publish command for Quarto Pub. (In case of first publish, the command will prompt you to authenticate)

The content will be rendered and published on Quarto Pub, opening in a browser for your viewing.

Publishing Using Quarto Pub

Quarto Publish Command - Management


  • Customizing Options: alter behavior of quarto publish using the following options in the command line

  • Site Management: change the “slug” (or URL path) of a published site, make a site the default one, or remove the site entirely using the site management interface at https://quartopub.com

Publishing Using Quarto Pub

Quarto Publish Command - Management


  • Multiple Accounts: ensure being logged into the correct Quarto Pub account before publishing from the CLI

  • Access Tokens: Quarto Pub uses an access token to grant permission for publishing to your account. List and remove saved accounts using the quarto publish accounts command, and view or revoke access tokens from the admin interface.

Publishing Using Quarto Pub

Github Action


Recommended way of rendering and publishing your site, if you prefer execution to be automatically triggered from commits.

  • Step 1: Publish record by completing at least one publish using the quarto publish command.

  • Step 2: Check project directory for a _publish.yml file indicating your publishing destination

Publishing Using Quarto Pub

Github Action


  • Step 3: Freezing Computations - To make sure that your R code is only executed locally, configure your project to use Quarto’s freeze feature by adding freeze: auto to your _quarto.yml.

Learn More Here


  • https://quarto.org
  • https://github.com/mcanouil/awesome-quarto


Optional Resources

  1. https://rstudio-conf-2022.github.io/rmd-to-quarto/materials/1-welcome-to-quarto/
  2. https://mine.quarto.pub/hello-quarto/#/hello-quarto-title
  3. https://www.youtube.com/watch?v=hbf7Ai3jnxY
  4. https://happygitwithr.com (for collaboration in Quarto)

Appendix

  1. Bray, A. (n.d.). From R Markdown to Quarto - Welcome to Quarto. Retrieved November 16, 2022, from https://rstudio-conf-2022.github.io/rmd-to-quarto/materials/1-welcome-to-quarto/

  2. Cetinkaya-Rundel, M. (n.d.). Hello Quarto. Quarto.Pub. Retrieved November 16, 2022, from https://mine.quarto.pub/hello-quarto/#/hello-quarto-title

  3. Mock, T. (2022, August 9). Welcome to Quarto Workshop! | Led by Tom Mock, RStudio. YouTube. https://www.youtube.com/watch?v=yvi5uXQMvu4

  4. Quarto. (n.d.). Quarto. Retrieved November 16, 2022, from https://quarto.org

This presentation has been made using the Quarto revealjs format.

Hertie School - Introduction to Data Science